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Extending an Object Class with a User-Defined Method 
and Implementing Error Handling 


By Rick Greenwald 


[ the first two articles of this series, we created a Pushbutton object class that 
can be used to call a report with a selection condition based on the value of a 
data field in a form. With this class, we can add its functionality to any form by 
simply dropping an instance of it into the form and setting several user-defined 
properties. [To create the Pushbutton object class, see Rick Greenwald’s “OPO 
Reports” and “OPO Reports: Part Il” in the February and March 1996 issues of 


Oracle Informant, respectively. ] 


The power of an object class comes from 
the re-use of its functionality. The more 
that instances can be used, the more the 
class contributes to the overall productivi- 
ty of a development effort. You should, 
therefore, create an object class so that it 
can be flexibly used in a wide variety of 
programming tasks. 


In this month’s article, we ll learn how to 
make class methods more granular, and in 
doing so, make the class more flexible. 
We'll also improve the class by adding 


some error handling to it. 


Feeling the Power of Object Classes 

In last month’s article, you created the 
clsReportPushbutton class. It nicely 
encapsulates the basic functionality required 
to call any report and limit the data that 
appears 1n a report. 


Until now, we have been using instances of 
our object class in the same manner that we 
would have copied and pasted an object and 
its functionality. We'll improve the class so 
that it can be used more flexibly. But what 
about the existing instances of the class? 


The real power of object classes becomes 
apparent when we want to modify the 
functionality of an object class and its 
instances. Any changes to the code in the 


object class are automatically inherited by 
all its instances when the applications con- 
taining the instances are recompiled. 


Since all the logic in a class is encapsulated 
within the class, developers can easily 
enhance and improve object classes with- 
out having to touch any of the instances. 
Provided we dont disturb the way the 
class interacts with its surrounding pro- 
gram, we dont have to worry about the 
changes we make that affect existing 
instances. As mentioned, you simply 
recompile the applications containing the 
instances to integrate class changes. 


Adding Flexibility to the 
clsReportPushbutton Class 

With the clsReportPushbutton class, you 
can drop an instance of it into your applica- 
tion, set the udpReport property to the name 
of the report you want to call, and then, set 
the udpSelectionObject property to the 
name of the object whose value you'll use to 
limit the selection of data in the report. The 
value in a data field object that is associated 
with the CUSTOMER_ID column, for 
example, can be used to restrict the report to 
only show the ORDERS associated with the 


current customer in the calling form. 


The first version of the 
clsReportPushbutton class assumed a 
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developer would associate the class with an object that is 
bound to a column in the table used by the called report. 


There may be times when a developer prefers to use a 
Pushbutton to call a report with a selection condition. 
However, the selection condition may be more complex than 
a simple equivalence with a single value from the database. In 
Oracle Power Objects (OPO), the fix to this is simple: By 
adding a user-defined method to the clsReportPushbutton 
class, we can implement the flexibility that allows developers 
to use our object class with virtually any selection condition. 


Creating a User-Defined Method 

As mentioned, all instances normally inherit the properties 
and methods of the object class. If you modify a property 
or add code to any inherited properties or methods in an 
instance of a class, the chain of inheritance between the 
object class and the instance for that property or method 
will be broken. In addition, any future changes to the 
properties or methods of the class will not be inherited by 
the instance of the class that modified them. 


When you add code to a method in a class, you can 
optionally call the code in the parent class with this syntax: 


Inherited.method_name 


This powerful feature of OPO enables you to easily extend 
the functionality of a class method while preserving the 
inheritance relationship between an instance and the class. 


You may have already accidentally experienced this feature 
of object classes when using the standard object classes. All 
the objects in the toolbar are actually object classes with 
their own inherited default methods. 


As with any instances of a class you create, the class method 
code does not appear in the code window of an instance. You 
add some code to what resembles an empty method, such as 
Open Window, and suddenly the window no longer opens! 
By adding code to the method and zot calling the inherited 
method in the basic class, you unknowingly prevented the 
default actions of the class method from working. 


With your own object classes, you're less likely to have 
this happen by accident. This is because OPO provides a 
clear visual marker of overridden properties and methods. 
In the Property sheet, the arrow to the left of the proper- 
ty or method name is black if the associated class value 
was overridden (see Figure 1). You can also reinherit the 
class values for properties or methods by clicking on the 
Reinherit button in the Property sheet’s toolbar. 


Because of these factors, you want to ensure that any func- 
tionality that may be commonly overridden in an instance 
of a class is in its own method. By doing this, a developer 
can replace it without having to remember to inherit any 
other necessary functionality in the class. 


pbReport Properties 


In the next version of = | 
clsReportPushbutton, we'll a1 
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Figure 1: The Property sheet 
with overridden properties. 


the selection condition to 
the logic in the ChildClick 
method. By doing this, we 
avoid hard-coding how the 
selection condition is derived 
from the object specified in 
the instance’s 
udpSelectionObject proper- 
ty. First, however, we'll cre- 
ate a user-defined method, 





similar to how we created a 
user-defined property. 


Step 1: Open the User Properties dialog box by clicking 
on the User Properties button in the Property sheet’s 
toolbar. Place the cursor in the first column of the blank 
row at the bottom of the table labeled Name. Enter 
udmSelectionCondition for the Name of the user- 
defined method, Function in the Type column, and 
String in the Datatype column. Figure 2 shows the User 
Properties dialog box with our user-defined method. 


User Properties 
| Name | Type | Datatype | Arguments 
__ Documentation Sub 
Property 
Property 
Property 


udpChangesChecked 


udpReport 
udpSelectionObject 
udmSelectionCondition Function 





Figure 2: The User Properties dialog box with the 
udmSelectionCondition method defined. 


The OPO style guide suggests using “udm” as the 
default prefix for user-defined methods. A user-defined 
method returns a value. For udmSelectionCondition, 
this value will be a string that represents the selection 
condition to be assigned to the DefaultCondition prop- 
erty of the called report. 


Note that we are defining a method, not a function. A 
method is a routine associated with an object. The 
udmSelectionCondition method will be added to our 
object class. 


Step 2: Open the window for the clsReportPushbutton 
class. Arrange your work area so you can see the User 
Properties window as well as the window and Property sheet 
for the clsReportPushbutton class (see Figure 3). Click 
on the row header to the left of the udmSelectionCondition 
method and drag it to the Property sheet for the class. 
Release the mouse when the cursor is over the class Property 
sheet to add the method to the class. 


Now, you can add code for the method. The class code for 
the method should return the same selection condition 
that was built in the earlier version of the class, since that 
is what the existing instances of your class expect. 
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Figure 3: Adding the udmSelectionCondition method to the 
clsReportPushbutton class. 


Step 3: Open the code window for the udmSelection- 
Condition method of the clsReportPushbutton class. 
Enter the following code: 


udmSelectionCondition = udpSelectionObject.DataSource & & 
"= '" & udpSelectionObject.Value & "'" 


You return a value from a method by setting the method’s 
name to the value you want to return. This code will 
return the same selection condition that was implemented 
in the code for the previous version of the class. 


Your next step is to modify the code in the ChildClick 
method of the class to add the return value from the 
udmSelectionCondition method. 


Step 4: Open the code window for the ChildClick 
method of the clsReportPushbutton class. Modify the 
first line of code so that it resembles this: 


udpReport.DefaultCondition = udmSelectionCondition() 
udpReport.OpenPreview( ) 


The default functionality of the new version of the 
clsReportPushbutton class will work exactly as the previ- 
ous version. However, to assign a different type of selection 
condition, simply override the udmSelectionCondition 
method without disturbing anything else in the class. Most 
importantly, you will not break the inheritance between 
other methods in the class and the instance. Therefore, 
future changes to those other methods are automatically 
inherited. 


Using Complex Selection Criteria 

Let’s add an instance of the class that will create a more 
complex selection condition for the report. We'll give the 
user the option to limit the report to orders from the cur- 
rently displayed sales representative, the currently dis- 
played state, and both or neither of these. 


Step 5: Open the frmOrders form used to launch the 
reports created in last month’s article. (This form and 
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Figure 4: An order form with check boxes and an instance of 
clsReportPushbutton. 


the original version of clsReportPushbutton are 
available for download from the Oracle Informant Works 
CD see end of article for details.) Delete last month’s 
instance of the clsReportPushbutton class. 


Step 6: Add a check box to the right of the top line of 
data fields in the report (see Figure 4). Set the Name 
property of the check box to cbSelectState and the 
Label property to State?. (You may have to enlarge the 
label area of the check box to display it all.) Set the 
Datatype property to String and ValueOn property 
to X. 


The user will check this box to indicate that he/she wants 
to limit the orders displayed in the report by the current 
value in the State data field. 


Step 7: Add another check box below the 
cbSelectState check box. Set the Name property of 
the check box to cbSelectSalesRep, the Label prop- 
erty to Sales Rep?, the Datatype property to String, 
and the ValueOn property to X. 


By using check boxes to indicate potential selection condi- 
tions, you allow the user to select either condition, both 
conditions, or no selection condition. 


Step 8: Rearrange your work space so you can see the 
application window and your form. Add an instance of the 
clsReportPushbutton class by clicking on the class icon 
and dragging it onto your form. 


The instance of the clsReportPushbutton class is, by 
default, placed in the upper-left corner of the form. 


Step 9: Move the instance of clsReportPushbutton to 
an area below your two check boxes. Set the Name prop- 
erty of the class to insCallReport to distinguish it as an 
instance and set the Label property to Run Report. Set 
the udpReport property to SampleReport, which is the 
report we designed in Part I of this series. 
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Step 10: Click on the class instance to select it and then 
click inside the insCallReport instance. Change the Label 
property of the Pushbutton to Call Select Report. 


Now you have all the required objects to implement a 
slightly sophisticated way of adding selection conditions to 
your report. Next, we'll modify the functionality of the 
instance to adapt it to your specific needs. 


Overriding Inherited Functionality 

We're ready to override the inherited udmSelectionCondition 
method with code that will create a selection condition based 
on the value of the check boxes in the form. 


Step 11: Open the code window for the 
udmSelectionCondition method of the insCallReport 
instance. Enter the following code: 


DIM strSelection AS String 

IF cbSelectState.Value = "X" THEN & 
strSelection = "STATE = '" & STATE.Value & "'" 
IF cbSelectSalesRep.Value = "X" THEN 

IF strSelection <> "" THEN strSelection = & 


strSelection " AND " strSelection =strSelection & & 
"SALES REP_ID ='" & SALES REP_ID.Value & "'" 
END IF 


udmSelectionCondition = strSelection 


First, the code sees if the user checked the cbSelectState 
check box to have a selection condition based on the value 
of the STATE data field. Then the code checks if the user 
wanted a selection condition based on the SALES REP ID 
data field. If so, the code checks if the strSelection con- 
dition contained a value because that would require the two 
selection conditions to be joined with AND. Finally, the 
selection condition is returned from the method. 


The rest of the class’ functionality remains intact. More 
importantly, if we decide to modify the existing function- 
ality in the class, the inheritance chain will allow this 
instance to inherit the changes. 


The final step in completing our class will be to imple- 
ment error handling to prevent user and developer errors. 


Error Handling 

We have created a flexible object class that any develop- 
er can easily use, but our task is not yet finished. For 
any piece of software, implementing functionality is 
just the first part of a job. Before releasing the software, 
you must ensure that it: 1) performs its intended job, 
and 2) doesnt do what it’s not supposed to do. Even if 
software is used improperly, it must fail gracefully. 


A class is no different from any other software component. It 
should be able to anticipate and handle any errors that might 
occur because of the faulty use of an instance of the class. 


The class you created will require an object handle in the 


udpSelectionObject property if you are using the default 


functionality of the udmSelectionCondition method. If a 
developer forgets to set the udpSelectionObject property, 
the instance of the class could develop run-time errors. You 
can avoid this by setting the DefaultCondition only if 
udpSelectionObject is not null. 


Step 12: Open the code window for the 
udmSelectionCondition method of clsReportPushbutton. 
Add the following IF statement as shown here: 


IF NOT ISNULL(udpSelectionObject) THEN & 
udmSelectionCondition = udpSelectionObject.DataSource & & 
"= '" & udpSelectionObject.Value & "'" 


This code will allow instances of the class to be used with 
a valid object or no value for the udpSelectionObject 
property. In the real world, you would probably also want 
to ensure that the value of udpSelectionObject is also a 


valid object handle. 


This error checking applies to the default code for the 
udmSelectionCondition method. You'll also want to add 
additional error checking to ensure that a value exists for 


the udpReport property. 


Step 13: Open the code window for the ChildClick 
method for clsReportPushbutton. Implement the code 
as shown here to check for the existence of a value for the 


udpReport property: 


IF NOT ISNULL(udpReport) THEN 
udpReport.DefaultCondition = udmSelectionCondition() 
udpReport.OpenPreview( ) 


ELSE 
MSGBOX("You must have a report specified.", 16, & 
"No Report" ) 
pbReport.Enabled = False 
END IF 


I always like the visual representation of an object to be 
meaningful. In this case, we are disabling the 
Pushbutton after we determine that the udpReport 
property does not contain a value. The Pushbutton’s 
disabled appearance will visually remind the user that 
it’s inactive. We could have added code to the OnLoad 
method of the class to see if the udpReport property 
was null, and then disabled or hidden the Pushbutton. 
However, this technique would have prevented an 
unsuspecting user from ever discovering what was 
wrong and notifying the developer. 


Notice how encapsulating logic with udmSelectionCondition 
works with inheritance to provide flexible functionality. The 
default udmSelectionCondition requires an object for 
udpSelectionObject to work properly. When we override the 
udmSelectionCondition method, we'll no longer need a 
value for udpSelectionObject. The code we use to override 
the method will be responsible for ensuring that its own pre- 
requisites are met, since these may be quite different for vari- 
ous instances. 
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In contrast, the entire clsReportPushbutton class will be 
useless without a report specified in the udpReport prop- 
erty. We place error checking for this condition in the 


basic ChildClick processing for the class. 


As your class is used more frequently, other errors will 
probably arise. Thankfully, the power of object orientation 
will allow you to continually enhance the error handling 
and functionality of the class and have its instances auto- 
matically inherit the improvements. 


Conclusion 

Next month, we'll look at some features in the 1.0.16 
release of Oracle Power Objects and explore how they can 
help us to implement wide ranging general functionality 
in object classes. Gil 


The demonstration objects referenced in this article are available 
on the Oracle Informant Works CD located in 
INFORM\96\APR\O19604RG. 
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